<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Our coding style &mdash; SIMULATeQCD 0.7 documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="../_static/togglebutton.css" type="text/css" />
      <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/underscore.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/togglebutton.js"></script>
        <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="How to do pull requests" href="git.html" />
    <link rel="prev" title="Contributions" href="contributions.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #343131" >
            <a href="../index.html" class="icon icon-home"> SIMULATeQCD
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../01_gettingStarted/gettingStarted.html">Getting started</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contributions.html">Contributions</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Our coding style</a></li>
<li class="toctree-l2"><a class="reference internal" href="git.html">How to do pull requests</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeStructure.html">General structure of the code</a></li>
<li class="toctree-l2"><a class="reference internal" href="templates.html">Template instantiation</a></li>
<li class="toctree-l2"><a class="reference internal" href="terminalIO.html">Terminal output &amp; terminating the program</a></li>
<li class="toctree-l2"><a class="reference internal" href="timer.html">Timing your code</a></li>
<li class="toctree-l2"><a class="reference internal" href="inputParameter.html">How to make an input parameter file</a></li>
<li class="toctree-l2"><a class="reference internal" href="memoryAllocation.html">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="multiGPU.html">Multi-GPU: Distribution of local lattices on the individual GPUs</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing the code</a></li>
<li class="toctree-l2"><a class="reference internal" href="documenting.html">Documenting your code</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../03_applications/applications.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../04_codeBase/codeBase.html">Code base</a></li>
<li class="toctree-l1"><a class="reference internal" href="../05_modules/modules.html">Modules</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: #343131" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">SIMULATeQCD</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
          <li><a href="contributions.html">Contributions</a> &raquo;</li>
      <li>Our coding style</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/02_contributions/codeStyle.md.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section class="tex2jax_ignore mathjax_ignore" id="our-coding-style">
<h1>Our coding style<a class="headerlink" href="#our-coding-style" title="Permalink to this headline"></a></h1>
<p>SIMULATeQCD exists in a space of many lattice codes, all of which perform extremely well, many of which are favorites
for large collaborations. Besides being one of the only lattice codes supporting multiple HISQ GPUs for multiple APIs,
the main reason to use SIMULATeQCD at all is that it’s readable, well structured, and for relatively simple computing
clusters works “out of the box”.</p>
<p>In order for our code to stay this way, we need you to please follow these coding practices to the best of your
ability when you make contributions.</p>
<section id="warnings">
<h2>Warnings<a class="headerlink" href="#warnings" title="Permalink to this headline"></a></h2>
<p>Switch on compiler warnings with -Wall -Wextra. Do care about these warnings. A code should compile without any warning.
If a warning is unavoidable use pragmas to suppress them.</p>
</section>
<section id="do-not-repeat-yourself">
<h2>Do not repeat yourself<a class="headerlink" href="#do-not-repeat-yourself" title="Permalink to this headline"></a></h2>
<p>Do not copy code or use similar code all the time. This makes it harder to maintain the code, for example by requiring the developer
to make the same change in multiple places.</p>
</section>
<section id="do-not-use-the-new-and-delete-operators">
<h2>Do not use the new and delete operators<a class="headerlink" href="#do-not-use-the-new-and-delete-operators" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">new</span></code> and the <code class="docutils literal notranslate"><span class="pre">delete</span></code> operators are a source for many errors, especially memory leaks. It is better to avoid them completely and
use the <a class="reference internal" href="memoryAllocation.html"><span class="doc std std-doc">Memory Manager</span></a>. There is absolutely no reason to use <code class="docutils literal notranslate"><span class="pre">new</span></code> for small objects. (Most objects are small.
Even the GPU-Memory classes are small: They only contain pointers to the memory. The allocated memory itself is not part of the class.)
Use the initialization list to create class members instead. The only case we have found where <code class="docutils literal notranslate"><span class="pre">new</span></code> and <code class="docutils literal notranslate"><span class="pre">delete</span></code> operators are
acceptable is with trees.</p>
</section>
<section id="avoid-pointers">
<h2>Avoid pointers<a class="headerlink" href="#avoid-pointers" title="Permalink to this headline"></a></h2>
<p>Avoid pointers where you can. Use references instead. Pointer arithmetic is difficult to read and pointers are not type safe.
This causes a lot of errors. There are cases where pointers are necessary (GPU memory). Everywhere else they should be avoided completely.</p>
</section>
<section id="delete-the-copy-constructor-for-classes-which-manage-large-amounts-of-memory">
<h2>Delete the copy constructor for classes which manage large amounts of memory<a class="headerlink" href="#delete-the-copy-constructor-for-classes-which-manage-large-amounts-of-memory" title="Permalink to this headline"></a></h2>
<p>Delete the copy constructor using
<code class="docutils literal notranslate"><span class="pre">myClass(myClass&amp;</span> <span class="pre">)</span> <span class="pre">=</span> <span class="pre">delete</span></code>.
The default copy constructor does not copy memory that is not part of the class. However, it calls the destructor. This deletes
the memory that the class points to. This can lead to bad memory accesses. Implement a move constructor instead.</p>
</section>
<section id="only-functions-should-be-public">
<h2>Only functions should be public<a class="headerlink" href="#only-functions-should-be-public" title="Permalink to this headline"></a></h2>
<p>Do not use public member variables in classes.</p>
</section>
<section id="use-const-whenever-possible">
<h2>Use const whenever possible<a class="headerlink" href="#use-const-whenever-possible" title="Permalink to this headline"></a></h2>
<p>The usage of <code class="docutils literal notranslate"><span class="pre">const</span></code> can help avoid undesired modification of objects.</p>
</section>
<section id="proper-naming">
<h2>Proper naming<a class="headerlink" href="#proper-naming" title="Permalink to this headline"></a></h2>
<p>Use proper and consistent naming for everything. Use the same name for file names as for the classes they contain. Use long names
which describe what is done. Do not use different names between different function calls. Follow the following naming scheme:</p>
<ul class="simple">
<li><p>Classes:
<code class="docutils literal notranslate"><span class="pre">ThisIsMyClass</span></code></p></li>
<li><p>Private class members:
<code class="docutils literal notranslate"><span class="pre">_my_member</span></code></p></li>
<li><p>Member function:
<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">thisIsMyFunction()</span></code></p></li>
<li><p>Function parameter:
<code class="docutils literal notranslate"><span class="pre">this_is_my_parameter</span></code></p></li>
</ul>
</section>
<section id="formatting">
<h2>Formatting<a class="headerlink" href="#formatting" title="Permalink to this headline"></a></h2>
<p>These are the conventions we have chosen for SIMULATeQCD. Please stick to them. Besides making the code a bit more readable,
it will look more professional if we all follow the same conventions.</p>
<ul class="simple">
<li><p>DO NOT USE TABS. Instead, please indent using 4 spaces.</p></li>
<li><p>Try for a maximum line length of 120ish characters, unless doing so hurts readability in an IDE.</p></li>
<li><p>Try for a maximum function length of 80ish lines.</p></li>
<li><p>Use braces:</p></li>
</ul>
<div class="highlight-C++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">10</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// instead of</span>
<span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">10</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>

<span class="c1">// An exception we allow is spacetime loops of the form</span>
<span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">Ns</span><span class="p">;</span><span class="w"> </span><span class="n">x</span><span class="o">++</span><span class="p">)</span><span class="w"></span>
<span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">Ns</span><span class="p">;</span><span class="w"> </span><span class="n">x</span><span class="o">++</span><span class="p">)</span><span class="w"></span>
<span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">Ns</span><span class="p">;</span><span class="w"> </span><span class="n">x</span><span class="o">++</span><span class="p">)</span><span class="w"></span>
<span class="k">for</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">Nt</span><span class="p">;</span><span class="w"> </span><span class="n">x</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">  </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ul class="simple">
<li><p>Do not put multiple statements in one line:</p></li>
</ul>
<div class="highlight-C++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// instead of</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ul class="simple">
<li><p>Please format your if-else statements like so:</p></li>
</ul>
<div class="highlight-C++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ul class="simple">
<li><p>Please use one of the following formats for initializer lists, taken from <a class="reference external" href="https://google.github.io/styleguide/cppguide.html">Google</a>:</p></li>
</ul>
<div class="highlight-C++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// When everything fits on one line:</span>
<span class="n">MyClass</span><span class="o">::</span><span class="n">MyClass</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">var</span><span class="p">)</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">some_var_</span><span class="p">(</span><span class="n">var</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// If the signature and initializer list are not all on one line,</span>
<span class="c1">// you must wrap before the colon and indent 4 spaces:</span>
<span class="n">MyClass</span><span class="o">::</span><span class="n">MyClass</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">var</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="o">:</span><span class="w"> </span><span class="n">some_var_</span><span class="p">(</span><span class="n">var</span><span class="p">),</span><span class="w"> </span><span class="n">some_other_var_</span><span class="p">(</span><span class="n">var</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// When the list spans multiple lines, put each member on its own line</span>
<span class="c1">// and align them:</span>
<span class="n">MyClass</span><span class="o">::</span><span class="n">MyClass</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">var</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="o">:</span><span class="w"> </span><span class="n">some_var_</span><span class="p">(</span><span class="n">var</span><span class="p">),</span><span class="w">             </span><span class="c1">// 4 space indent</span>
<span class="w">      </span><span class="n">some_other_var_</span><span class="p">(</span><span class="n">var</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">  </span><span class="c1">// lined up</span>
<span class="w">    </span><span class="p">...</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
</section>
<section id="write-helpful-comments">
<h2>Write helpful comments<a class="headerlink" href="#write-helpful-comments" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>Give comments about complex sections, tricks that you used, relevant visualizations, DOIs for papers, your design philosophy (when relevant), etc.
DO NOT comment trivial code. Remove commented-out code. (It is anyway in the git history if we need it later.)</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">SIMULATeQCD/scripts/comments.bash</span></code> to put some leading comments at the top of your code. This helps ensure that we all include the same
information in the same way at the beginning of our code.</p></li>
</ul>
</section>
<section id="remove-old-features">
<h2>Remove old features<a class="headerlink" href="#remove-old-features" title="Permalink to this headline"></a></h2>
<p>If features are not needed any more, remove them.</p>
</section>
<section id="use-c-11-14-17-20-features">
<h2>Use <code class="docutils literal notranslate"><span class="pre">C++11/14/17/20</span></code> features<a class="headerlink" href="#use-c-11-14-17-20-features" title="Permalink to this headline"></a></h2>
<p>Lambda expressions, initializer lists, move constructors, and so on. Read about them. They are nice!</p>
</section>
</section>


           </div>
          </div>
          <footer>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2021, LatticeQCD.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>